package com.winsdom.service.customer;

import com.winsdom.entity.customer.CustomerPersonalCreateRequest;
import com.winsdom.service.customer.impl.CustomerPersonalCreateServiceImpl;

/**
 * 个人客户创建服务接口
 * <p>
 * 该接口负责处理个人客户的完整创建流程，包括：
 * 1. 客户主表数据插入
 * 2. 个人扩展信息（证件类型、证件号码等）插入
 * 3. 证件图片信息管理
 * 4. 联系人及关联楼盘分类关系维护
 * <p>
 * 所有操作在一个事务中执行，确保数据一致性。
 * 成功创建后返回新生成的客户ID。
 */
public interface CustomerPersonalCreateService {

    /**
     * 创建个人客户的完整业务流程
     * <p>
     * 执行顺序：
     * 1. 校验并设置客户类型为个人（类型码3）
     * 2. 插入客户主表数据并获取自增ID
     * 3. 插入个人扩展信息（如证件类型、证件号码）
     * 4. 插入证件图片路径（如果提供）
     * 5. 处理联系人信息及关联的楼盘分类（支持多联系人，自动去重楼盘名称）
     * <p>
     * 数据规范：
     * - 传入的{@link CustomerPersonalCreateRequest}对象需包含客户基础信息，
     *   其中updateUserId（操作人ID）为必填项
     * - 客户类型将被强制设置为个人（类型码3），不可修改
     * - 联系人关联的楼盘名称将自动去重，避免重复关联
     *
     * @param request 个人客户创建请求实体，包含完整的客户创建数据（非null）
     * @return 新创建的客户ID（数据库自增主键）
     * @throws IllegalArgumentException 当request为null或必填字段缺失时抛出
     * @see CustomerPersonalCreateRequest
     * @see CustomerPersonalCreateServiceImpl
     */
    Long create(CustomerPersonalCreateRequest request);
}